.TH "ggi_directbuffer" 3 "2007-06-24" "libggi-current" GGI
.SH NAME
\fBggi_directbuffer\fR, \fBggi_pixellinearbuffer\fR, \fBggi_pixelplanarbuffer\fR, \fBggi_samplelinearbuffer\fR, \fBggi_sampleplanarbuffer\fR : LibGGI direct buffer structure description
.SH SYNOPSIS
.nb
.nf
#include <ggi/ggi.h>

typedef struct {
      uint32_t                type;
      int             frame;

      ggi_resource_t  resource;

      void            *read;
      void            *write;

      unsigned int    page_size;
      uint32_t                noaccess;       
      uint32_t                align;

      ggi_bufferlayout        layout;

      union {
              ggi_pixellinearbuffer plb;
              ggi_pixelplanarbuffer plan;
              ggi_samplelinearbuffer slb;
              ggi_sampleplanarbuffer splan;
              void *extended;
      } buffer;
} ggi_directbuffer;
.fi

.SH DESCRIPTION
The \fBggi_directbuffer\fR structure contains information on
target-dependent buffers to allow applications to access them
directly.
.SH STRUCTURE MEMBERS
\fItype\fR
.RS
.nb
.nf
/* Buffer types */
#define GGI_DB_NORMAL      0x0001  /* "frame" is valid when set */
#define GGI_DB_EXTENDED    0x0002
#define GGI_DB_MULTI_LEFT  0x0004
#define GGI_DB_MULTI_RIGHT 0x0008

/* Flags that may be or'ed with the buffer type */
#define GGI_DB_SIMPLE_PLB   0x01000000
/* GGI_DB_SIMPLE_PLB means that the buffer
   has the following properties:
  type == GGI_DB_NORMAL
  read == write
  noaccess == 0
  align == 0
  layout == blPixelLinearBuffer
*/
.fi

.RE
.TP
\fIframe\fR
is the frame number as used in multiple buffering.  Note that each
frame can export more than one DirectBuffer.

.TP
\fIresource\fR
is a pointer to a lowlevel resource. Certain DirectBuffers need to
be explicitly acquired (i.e. locked) before using them
(i.e. accessing their pointers).  Such a situation may arise if
the underlying visual supports mixed acceleration and framebuffer
access, but they cannot occur at the same time.  In that case,
LibGGI needs to be informed when the application is using the
framebuffer.

You can determine whether the DirectBuffer needs to be acquired by
using \fBggiResourceMustAcquire(3)\fR.  An acquire is done by using
\fBggiResourceAcquire(3)\fR and it is released by calling
\fBggiResourceRelease(3)\fR.

.TP
\fIread\fR, \fIwrite\fR
are the addresses where the buffer is mapped to the application.
Read and write access to the buffer is done using load and store
instructions of the host CPU. Read operations should be performed
using the \fIread\fR buffer and write operations should be performed
using the \fIwrite\fR buffer. These might be the same, but need
not. If they are, read/write may be done to either buffer. Please
note, that either read or write may be \fBNULL\fR. These are
write-only or read-only buffers, which might be caused by hardware
limitations. Such buffers are not suited to do Read-Modify-Write
operations, so take care.

Be aware that these fields may be changed by an acquire, and that
they may be \fBNULL\fR or invalid when the DirectBuffer is not
acquired.

.TP
\fIpage_size\fR
indicates a Paged buffer if not \fB0\fR.

Successive access to addresses \fBaddr0\fR and \fBaddr1\fR of either read
or write buffers with \fBaddr0\fR/\fBpage_size\fR != \fBaddr1\fR/\fBpage_size\fR
may be very expensive compared to successive accesses with
\fBaddr0\fR/\fBpage_size\fR == \fBaddr1\fR/\fBpage_size\fR.

On i386 the penalty will be about 1500 cycles plus 4 cycles per to
be remapped. Because of this, block transfer operations might
become very inefficient for paged buffers. If there are two
different buffers provided for read and write operations, you
should do successive reads from one and do successive writes to
the other. If not, it is recommended to copy pagewise into a
temporary buffer and then to copy this temporary buffer back to
screen.

.TP
\fInoaccess\fR
is a bitfield specifying an access restriction. When bit x is set,
you may not access this DirectBuffer at the width of 2^x bytes. It
is usually 0, but check it.

.TP
\fIalign\fR
is a bitfield specifying another access restriction.  When bit x
is set, you may only access this DirectBuffer at the width of 2^x
bytes, when the access is aligned to a multiple of 2^x. Note that
bit 0 is a bit bogus here, but it should be always 0, as then
((noaccess|align)==0) is a quick check for "no restrictions".

.TP
\fIlayout\fR
is an enumeration specifying the buffer addressing scheme.
Possible values are \fBblPixelLinearBuffer\fR, \fBblPixelPlanarBuffer\fR,
\fBblExtended\fR, \fBblSampleLinearBuffer\fR and \fBblSamplePlanarBuffer\fR.
See below for their definition.

.TP
\fIbuffer\fR
is a union of all buffer info.  Check the \fBlayout\fR member to see
which member of use.

.PP
.SH PIXEL LINEAR BUFFER
.nb
.nf
typedef struct {
      int             stride;         /* bytes per row                */
      ggi_pixelformat *pixelformat;   /* format of the pixels         */
} ggi_pixellinearbuffer;
.fi

A linear buffer is a region in the application's virtual memory
address space. A pixel with the pixel coordinates (\fIx\fR, \fIy\fR) is
assigned a pixel number according to the following formula:

.nb
.nf
pixel_number = (origin_y + y) * stride + origin_x + x;
.fi

In any case both \fBx\fR and \fBy\fR must not be negative, and less than the
buffer's width and height respectively. For top-left-origin screen
coordinates, \fBstride\fR and \fBorigin_y\fR will both be positive. For
bottom-left-origin screen coordinates, \fBstride\fR and \fBorigin_y\fR will
both be negative. This will result in the correct pixel number with
the same formula in both cases. The pixel number will be used to
address the pixel.

A certain number of bits is stored per pixel, and this is indicated in
the \fBggi_pixelformat.access\fR field.  For some visuals, the buffer
might not be in host CPU native format and swapping operations need to
be performed before writes or after reads.
.SH PIXEL PLANAR BUFFER
.nb
.nf
typedef struct {
      int             next_line;      /* bytes until next line        */
      int             next_plane;     /* bytes until next plane       */
      ggi_pixelformat *pixelformat;   /* format of the pixels         */
} ggi_pixelplanarbuffer;
.fi

.SH SAMPLE LINEAR BUFFER
.nb
.nf
typedef struct {
      int             num_pixels;     /* how many pixelformats        */
      int             stride;         /* bytes per row                */
      ggi_pixelformat *pixelformat[4];/* format of the pixels         */
} ggi_samplelinearbuffer;
.fi

.SH SAMPLE PLANAR BUFFER
.nb
.nf
typedef struct {
      int             next_line[3];   /* bytes until next line        */
      int             next_plane[3];  /* bytes until next plane       */
      ggi_pixelformat *pixelformat[4];/* format of the pixels         */
} ggi_sampleplanarbuffer;
.fi

.SH EXTENDED BUFFER
TODO : write something here.
.SH SEE ALSO
\f(CWggi_pixelformat(3)\fR, \f(CWggiDBGetBuffer(3)\fR, \f(CWggiResourceAcquire(3)\fR
